🔔 API de Alertas e Notificações - Documentação Completa

📋 Visão Geral

A API de Alertas e Notificações é responsável por toda a gestão de alertas do sistema e envio de notificações push no CordenaAi. Esta API permite criar, consultar e gerenciar alertas para usuários específicos, além de enviar notificações push para dispositivos móveis e processar alertas periódicos para mensagens não lidas.

🎯 Endpoints Disponíveis

📝 Alertas

1. GET /api/alertas

Listar Todos os Alertas

2. POST /api/alertas

Criar Novo Alerta

3. GET /api/alertas/{id}

Obter Alerta por ID

4. DELETE /api/alertas/{id}

Excluir Alerta

5. POST /api/alertas/{id}/marcar-como-lida

Marcar Alerta como Lido

6. GET /api/alertas/usuario/{identificador}

Obter Alertas por Usuário

7. GET /api/alertas/usuario/{identificador}/nao-lidos

Obter Alertas Não Lidos por Usuário

📱 Notificações

1. POST /api/notificacoes/push

Enviar Notificação Push

2. POST /api/notificacoes/mensagem/{mensagemId}

Enviar Notificação para Mensagem

3. POST /api/notificacoes/alertas-periodicos

Processar Alertas Periódicos

🔧 Modelo de Dados

Estrutura do Alerta

{
  "id": "integer",
  "conteudo": "string",
  "tipo": "string",
  "leitura": "string",
  "dataCriacao": "datetime",
  "dataAtualizacao": "datetime",
  "destinatarioId": "string",
  "usuarioAtualizadorId": "string",
  "usuarioAtualizacao": "string",
  "status": "string"
}

Estrutura da Notificação Push

{
  "usuarioIds": ["string"],
  "titulo": "string",
  "mensagem": "string",
  "dados": "object"
}

Estrutura de Criação de Alerta

{
  "conteudo": "string",
  "tipo": "string",
  "destinatarioId": "string"
}

Estrutura de Pesquisa de Alertas

{
  "destinatarioId": "string",
  "tipo": "string",
  "leitura": "string",
  "status": "string",
  "dataInicio": "datetime",
  "dataFim": "datetime",
  "pagina": "integer",
  "tamanhoPagina": "integer"
}

🔐 Autenticação e Autorização

Todos os endpoints requerem:

📊 Casos de Uso Principais

1. Criação de Alerta Administrativo

POST /api/alertas
Content-Type: application/json
Authorization: Bearer {token}

{
  "conteudo": "Sistema será atualizado às 02:00",
  "tipo": "ALERTA",
  "destinatarioId": "user-123"
}

2. Envio de Notificação Push

POST /api/notificacoes/push
Content-Type: application/json
Authorization: Bearer {token}

{
  "usuarioIds": ["user-123", "user-456"],
  "titulo": "Nova Mensagem",
  "mensagem": "Você recebeu uma nova mensagem",
  "dados": {
    "mensagemId": 789,
    "tipo": "comunicado"
  }
}

3. Consulta de Alertas Não Lidos

GET /api/alertas/usuario/user-123/nao-lidos
Authorization: Bearer {token}

4. Marcar Alerta como Lido

POST /api/alertas/456/marcar-como-lida
Authorization: Bearer {token}

⚠️ Validações e Regras de Negócio

Validações Obrigatórias

Regras de Negócio

🚨 Tratamento de Erros

Códigos de Status HTTP

Formato de Erro

{
  "error": "string",
  "message": "string",
  "details": "string",
  "timestamp": "datetime"
}

📈 Performance e Limitações

Limitações

Otimizações

🔄 Integração com Outros Módulos

Módulos Relacionados

📱 Uso em Aplicações

Web App

Mobile App

Sistema

🛠️ Manutenção e Monitoramento

Logs Importantes

Métricas Monitoradas

📚 Exemplos Práticos

Fluxo Completo de Criação de Alerta

  1. Validação de dados no backend pela própria API
  2. POST /api/alertas com dados validados
  3. Criação automática do alerta no sistema
  4. Envio de notificação push (se configurado)
  5. Registro de auditoria da operação

Fluxo de Notificação Push

  1. POST /api/notificacoes/push com lista de usuários
  2. Validação de usuários ativos e válidos
  3. Envio assíncrono para dispositivos móveis
  4. Registro de status de entrega
  5. Retry automático para falhas temporárias

Fluxo de Alertas Periódicos

  1. POST /api/notificacoes/alertas-periodicos (job agendado)
  2. Busca de mensagens não lidas
  3. Criação de alertas para usuários
  4. Envio de notificações push
  5. Registro de processamento no log

Versão: 1.0
Última Atualização: Outubro de 2025
Responsável: Equipe de Desenvolvimento CordenaAi